---
title: CLI Commands
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window.

### `astro` commands

Use the CLI by running one of the **commands** documented on this page with your preferred package manager, optionally followed by any **flags**. Flags customize the behavior of a command.

One of the commands you'll use most often is `astro dev`. This command starts the development server and gives you a live, updating preview of your site in a browser as you work:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # start the development server
  npx astro dev
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # start the development server
  pnpm astro dev
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # start the development server
  yarn astro dev
  ```
  </Fragment>
</PackageManagerTabs>

You can type `astro --help` in your terminal to display a list of all available commands:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro --help
  ```
  </Fragment>
</PackageManagerTabs>

The following message will display in your terminal:

```bash
astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
       create-key  Create a cryptography key
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate TypeScript types for all Astro modules.
      preferences  Configure user preferences.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --help  Show this help message.
```


You can add the `--help` flag after any command to get a list of all the flags for that command.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # get a list of all flags for the `dev` command
  npm run dev -- --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # get a list of all flags for the `dev` command
  pnpm dev --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # get a list of all flags for the `dev` command
  yarn dev --help
  ```
  </Fragment>
</PackageManagerTabs>

The following message will display in your terminal:

```bash
astro dev [...flags]

Flags
                 --port  Specify which port to run on. Defaults to 4321.
                 --host  Listen on all addresses, including LAN and public addresses.
--host <custom-address>  Expose on a network IP address at <custom-address>
                 --open  Automatically open the app in the browser on server start
                --force  Clear the content layer cache, forcing a full rebuild.
            --help (-h)  See all available flags.
```

:::note
The extra `--` before any flag is necessary for `npm` to pass your flags to the `astro` command.
:::

### `package.json` scripts

You can also use scripts in `package.json` for shorter versions of these commands. Using a script allows you to use the same commands that you may be familiar with from other projects, such as `npm run build`.

The following scripts for the most common `astro` commands (`astro dev`, `astro build`, and `astro preview`) are added for you automatically when you create a project using [the `create astro` wizard](/en/install-and-setup/).

When you follow the instructions to [install Astro manually](/en/install-and-setup/#manual-setup), you are instructed to add these scripts yourself. You can also add more scripts to this list manually for any commands you use frequently.

```json title="package.json"
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
```

You will often use these `astro` commands, or the scripts that run them, without any flags. Add flags to the command when you want to customize the command's behavior. For example, you may wish to start the development server on a different port, or build your site with verbose logs for debugging.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # run the dev server on port 8080 using the `dev` script in `package.json`
  npm run dev -- --port 8080

  # build your site with verbose logs using the `build` script in `package.json`
  npm run build -- --verbose
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # run the dev server on port 8080 using the `dev` script in `package.json`
  pnpm dev --port 8080

  # build your site with verbose logs using the `build` script in `package.json`
  pnpm build --verbose
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # run the dev server on port 8080 using the `dev` script in `package.json`
  yarn dev --port 8080

  # build your site with verbose logs using the `build` script in `package.json`
  yarn build --verbose
  ```
  </Fragment>
</PackageManagerTabs>

## `astro dev`

Runs Astro's development server. This is a local HTTP server that doesn't bundle assets. It uses Hot Module Replacement (HMR) to update your browser as you save changes in your editor.

The following hotkeys can be used in the terminal where the Astro development server is running:

- `s + enter` to sync the content layer data (content and types).
- `o + enter` to open your Astro site in the browser.
- `q + enter` to quit the development server.

## `astro build`

Builds your site for deployment. By default, this will generate static files and place them in a `dist/` directory. If any routes are [rendered on demand](/en/guides/on-demand-rendering/), this will generate the necessary server files to serve your site.

<h3>Flags</h3>

The command accepts [common flags](#common-flags) and the following additional flags:

#### `--devOutput`

<p><Since v="5.0.0" /></p>

Outputs a development-based build similar to code transformed in `astro dev`. This can be useful to test build-only issues with additional debugging information included.

## `astro preview`

Starts a local server to serve the contents of your static directory (`dist/` by default) created by running `astro build`.

This command allows you to preview your site locally [after building](#astro-build) to catch any errors in your build output before deploying it. It is not designed to be run in production. For help with production hosting, check out our guide on [Deploying an Astro Website](/en/guides/deploy/).

The following hotkeys can be used in the terminal where the Astro preview server is running:
- `o` + `enter` to open your Astro site in the browser.
- `q` + `enter` to quit the preview server.

The `astro preview` command can be combined with the [common flags](#common-flags) documented below to further control the preview experience.

## `astro check`

Runs diagnostics (such as type-checking within `.astro` files) against your project and reports errors to the console. If any errors are found the process will exit with a code of **1**.

This command is intended to be used in CI workflows.

<h3>Flags</h3>

Use these flags to customize the behavior of the command.

#### `--watch`

The command will watch for any changes in your project, and will report any errors.

#### `--root <path-to-dir>`

Specifies a different root directory to check. Uses the current working directory by default.

#### `--tsconfig <path-to-file>`

Specifies a `tsconfig.json` file to use manually. If not provided, Astro will attempt to find a config, or infer the project's config automatically.

#### `--minimumFailingSeverity <error|warning|hint>`

Specifies the minimum severity needed to exit with an error code. Defaults to `error`.

For example, running `astro check --minimumFailingSeverity warning` will cause the command to exit with an error if any warnings are detected.

#### `--minimumSeverity <error|warning|hint>`

Specifies the minimum severity to output. Defaults to `hint`.

For example, running `astro check --minimumSeverity warning` will show errors and warning, but not hints.

#### `--preserveWatchOutput`

Specifies not to clear the output between checks when in watch mode.

#### `--noSync`

Specifies not to run `astro sync` before checking the project.

<ReadMore>Read more about [type checking in Astro](/en/guides/typescript/#type-checking).</ReadMore>

## `astro sync`

<p><Since v="2.0.0" /></p>

:::tip
Running `astro dev`, `astro build` or `astro check` will run the `sync` command as well.
:::

Generates TypeScript types for all Astro modules. This sets up a [`.astro/types.d.ts` file](/en/guides/typescript/#setup) for type inferencing, and defines modules for features that rely on generated types:
- The `astro:content` module for the [Content Collections API](/en/guides/content-collections/).
- The `astro:db` module for [Astro DB](/en/guides/astro-db/).
- The `astro:env` module for [Astro Env](/en/guides/environment-variables/).
- The `astro:actions` module for [Astro Actions](/en/guides/actions/)

## `astro add`

Adds an integration to your configuration. Read more in [the integrations guide](/en/guides/integrations-guide/#automatic-integration-setup).

## `astro docs`

Launches the Astro Docs website directly from the terminal.

## `astro info`

Reports useful information about your current Astro environment. Useful for providing information when opening an issue.

```shell
astro info
```

Example output:

```
Astro                    v5.14.1
Vite                     v6.3.6
Node                     v22.17.1
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @astrojs/starlight (v0.35.3)
```

<h3>Flags</h3>

Use the following flags to customize the behavior of the command.

#### `--copy`

The command will copy the output to the clipboard without prompting.

## `astro preferences`

Manage user preferences with the `astro preferences` command. User preferences are specific to individual Astro users, unlike the `astro.config.mjs` file which changes behavior for everyone working on a project.

User preferences are scoped to the current project by default, stored in a local `.astro/settings.json` file.

Using the `--global` flag, user preferences can also be applied to every Astro project on the current machine. Global user preferences are stored in an operating system-specific location.

<h3>Available preferences</h3>

- `devToolbar` — Enable or disable the development toolbar in the browser. (Default: `true`)
- `checkUpdates` — Enable or disable automatic update checks for the Astro CLI. (Default: `true`)

The `list` command prints the current settings of all configurable user preferences. It also supports a machine-readable `--json` output.

```shell
astro preferences list
```

Example terminal output:

| Preference               | Value |
| ------------------------ | ----- |
| devToolbar.enabled       | true  <tr></tr>|
| checkUpdates.enabled     | true  |


You can `enable`, `disable`, or `reset` preferences to their default.

For example, to disable the devToolbar in a specific Astro project:

```shell
astro preferences disable devToolbar
```

To disable the devToolbar in all Astro projects on the current machine:

```shell
astro preferences disable --global devToolbar
```

The devToolbar can later be enabled with:

```shell
astro preferences enable devToolbar
```

The `reset` command resets a preference to its default value:

```shell
astro preferences reset devToolbar
```

## `astro telemetry`

Sets telemetry configuration for the current CLI user. Telemetry is anonymous data that provides the Astro team insights into which Astro features are most often used. For more information see [Astro's telemetry page](https://astro.build/telemetry/).

Telemetry can be disabled with this CLI command:

```shell
astro telemetry disable
```

Telemetry can later be re-enabled with:

```shell
astro telemetry enable
```

The `reset` command resets the telemetry data:

```shell
astro telemetry reset
```

:::tip[Want to disable telemetry in CI environments?]
Add the `astro telemetry disable` command to your CI scripts or set the `ASTRO_TELEMETRY_DISABLED` environment variable.
:::

## `astro create-key`

Generates a key to encrypt props passed to server islands.

```shell
astro create-key
```

Set this key as the `ASTRO_KEY` environment variable (e.g. in a `.env` file) and include it in your CI/CD or host’s build settings when you need [a constant encryption key for your server islands](/en/guides/server-islands/#reusing-the-encryption-key) for situations like rolling deployments, multi-region hosting or a CDN that caches pages containing server islands.

## Common flags

### `--root <path>`

Specifies the path to the project root. If not specified, the current working directory is assumed to be the root.

The root is used for finding the Astro configuration file.

```shell
astro --root myRootFolder/myProjectFolder dev
```

### `--config <path>`

Specifies the path to the config file relative to the project root. Defaults to `astro.config.mjs`. Use this if you use a different name for your configuration file or have your config file in another folder.

```shell
astro --config config/astro.config.mjs dev
```

### `--force <string>`

<p><Since v="5.0.0" /></p>

Clear the [content layer cache](/en/guides/content-collections/#defining-the-collection-loader), forcing a full rebuild.

### `--mode <string>`

<p><Since v="5.0.0" /></p>

Configures the [`mode`](/en/reference/programmatic-reference/#mode) inline config for your project.

### `--outDir <path>`

<p><Since v="3.3.0" /></p>

Configures the [`outDir`](/en/reference/configuration-reference/#outdir) for your project. Passing this flag will override the `outDir` value in your `astro.config.mjs` file, if one exists.

### `--site <url>`

Configures the [`site`](/en/reference/configuration-reference/#site) for your project. Passing this flag will override the `site` value in your `astro.config.mjs` file, if one exists.

### `--base <pathname>`

<p><Since v="1.4.1" /></p>

Configures the [`base`](/en/reference/configuration-reference/#base) for your project. Passing this flag will override the `base` value in your `astro.config.mjs` file, if one exists.

### `--port <number>`

Specifies which port to run the dev server and preview server on. Defaults to `4321`.

### `--host [optional host address]`

Sets which network IP addresses the dev server and preview server should listen on (i.e. non-localhost IPs). This can be useful for testing your project on local devices like a mobile phone during development.

- `--host` — listen on all addresses, including LAN and public addresses
- `--host <custom-address>` — expose on a network IP address at `<custom-address>`

:::caution
Do not use the `--host` flag to expose the dev server and preview server in a production environment. The servers are designed for local use while developing your site only.
:::

### `--allowed-hosts`

<p><Since v="5.4.0" /></p>

Specifies the hostnames that Astro is allowed to respond to in `dev` or `preview` modes. Can be passed a comma-separated list of hostnames or `true` to allow any hostname.

Refer to [Vite's `allowedHosts` feature](https://vite.dev/config/server-options.html#server-allowedhosts) for more information, including security implications of allowing hostnames.

### `--verbose`

Enables verbose logging, which is helpful when debugging an issue.

### `--silent`

Enables silent logging, which will run the server without any console output.

### `--open`

Automatically opens the app in the browser on server start. Can be passed a full URL string (e.g. `--open http://example.com`) or a pathname (e.g. `--open /about`) to specify the URL to open.

## Global flags

Use these flags to get information about the `astro` CLI.

### `--version`

Prints the Astro version number and exits.

### `--help`

Prints the help message and exits.
